PC Pro 2005 June (DVD)/DPPRO0605DVD.iso/Install/program files/Borland/BDS/3.0/Demos/Delphi.Net/CLR/SimplePrintout/README.TXT

Text File | 2004-10-22 | 12.7 KB | 363 lines

README.TXT
==========


What is SimplePrintout?
=======================

This directory contains a very simple printing class.

SimplePrintout unit provides a very basic printout for your
quick and dirty Delphi for .NET projects. Many times when
you sit down to write a tiny software project you feel like
there is no easy way of printing out relatively small amounts
of data.

Of course, .NET makes it easier to print text and pictures. However
the first time you need to print justified text or bordered text, or
pages with simple header or footer, you come to realize that you
still have to revert to counting pixels.

In many cases using a professional report generating tools
may be an overkill, but writing your own printing component
can be a daunting task too.

That is where SimplePrintout class comes into play.

SimplePrintout keeps all those details hidden from you. Although
it is not a full-blown reporting tool, you will be amazed just
how much you can accomplish with this little unit...



Installation
============

At the time of this writing SimplePrintout for Delphi for .NET
has some minor problems with code serialization. I need to clean
that up to make it into a component. So for now SimplePrintout
is provided as a Delphi unit, rather than an installable component.
As a result, it does not require any installation. Simply copy the
unit called Simp_Prn.PAS to your project directory and add
"Simp_Prn" to your unit's USES statement.

Don't forget to check Borland CodeCentral for the latest code
updates.



How to use SimplePrintout component?
====================================

The best way to find out about SimplePrintout is to compile and
run the DemoProj application. This demo application will get
you started.


Lesson 1.
--------
  You may simply create and use an instance of SimplePrintout at
  runtime. It is relatively easy. Start by adding "Simp_Prn" unit
  to your "uses" stament.

    procedure TWinForm.Button1_Click(sender: System.Object;
                                     e: System.EventArgs);
    VAR p: SimplePrintout;
        s: StreamReader;
    begin
      // It's very simple to create
      // a SimplePrintout...
      //
      p := SimplePrintout.Create();

      try
        // Always call BeginPrintout!
        //
        p.BeginPrintout();

        // And finally here is how to print out a text file...
        // This is much simpler than Microsoft .NET sample.
        //
        s := StreamReader.Create('c:\autoexec.bat');
        p.WriteString(s.ReadToEnd());
        s.Close();

        // Use this call to flush the text to the printer
        //
        p.EndPrintout();

        // NOTE: To cancel printout you may use
        //   p.AbortPrintout(); instead of p.EndPrintout();
        //
      except
        on E: Exception do
          MessageBox.Show(E.Message);
      end;
      p.Free; // with .NET you do not really need this one
    end;


Lesson 2.
--------
Let us add some meat to our sample code...

    procedure TWinForm.Button1_Click(sender: System.Object;
                                     e: System.EventArgs);
    VAR p: SimplePrintout;
        s: StreamReader;
    begin
      p := SimplePrintout.Create();

      try
        // Always call BeginPrintout!
        //
        p.BeginPrintout();

        // You may set margins (measured in inches)
        //
        p.TopMargin := 1.5; // leave some room for the header
        p.BottomMargin := 1; // leave some room for the footer

        // It is pretty easy to set footers and headers...
        //
        p.Header.Text := 'you can have'+#13#10+'multi-line HEADERS';
        p.Footer.TextIndentBottom := 0.3;
        p.Footer.Text := 'Footer text';

        // To align your paragraph text to Left,
        // simply set Band.TextAlignment to baLeft
        // (Your choices for alignment are:
        //  baLeft, baRight, baCentered, and baJustified
        //
        p.Band.TextAlignment := BandAlignment.baLeft;

        // This is how you can change fonts.
        // It's pretty striaghtforward.
        //
        p.Band.TextFont := System.Drawing.Font.Create('Arial', 12);

        // And finally here is how to print out a text file...
        // This is much simpler than Microsoft .NET sample.
        //
        s := StreamReader.Create('c:\autoexec.bat');
        p.WriteString(s.ReadToEnd());
        s.Close();

        // Use this call to flush the text to the printer
        //
        p.EndPrintout();

        // NOTE: To cancel printout you may use
        //   p.AbortPrintout(); instead of p.EndPrintout();
        //
      except
        on E: Exception do
          MessageBox.Show(E.Message);
      end;
      p.Free; // with .NET you do not really need this one
    end;

Lesson 3.
--------
  How to add Page numbering to the footer (or header). Or rather,
  let us paraphrase this question. How to make headers and footers
  more dynamic?

  All you need is to add an event handler like this:

    procedure TWinForm.on_PrintPage(sender: System.Object;
                              ua: UserPrintPageEventArgs);
    begin
      (sender as SimplePrintout).Footer.Text :=
        'Page ' + ua.PageNo.ToString;
    end;

    procedure TWinForm.Button1_Click(sender: System.Object;
                                     e: System.EventArgs);
    VAR p: SimplePrintout;
        s: StreamReader;
    begin
      p := SimplePrintout.Create();

      try
        // Always call BeginPrintout!
        //
        p.BeginPrintout();

        // Add our print page handler here
        //
        Include(p.PrintPage, on_PrintPage);

        s := StreamReader.Create('c:\autoexec.bat');
        p.WriteString(s.ReadToEnd());
        s.Close();

        p.EndPrintout();
      except
        on E: Exception do
          MessageBox.Show(E.Message);
      end;
    end;


Lesson 4.
--------
  We already know some methods and some properties of the SimplePrintout
  class. But there are other methods and properties you may want to use
  as you go.

     BeginPrintout  - use this call before calling any other methods.

     WriteString    - lets you print one string at the time. The string
                      can be as long as you want it to be. It will be
                      wrapped as necessary. This way you can put your
                      entire document into one string and send it to
                      printer with one command.

     PageBreak      - inserts a page break.

     EndPrintout    - this will flush data to the physical printer.

     AbortPrintout  - this will terminate output without printing
                      to physical device, if called instead of EndPrintout.

     Page setup:
       NonPrintableGutterSize - measured in inches.
                      Most printers do not let you print at
                      the very edge of the page. We set this
                      non-printable gutter size to 3/16" by default
                      The programmer can change this setting.

       TopMargin -    Top margin including the gutter, in inches
       LeftMargin -   Left margin including the gutter, in inches
       RightMargin -  Right margin including the gutter, in inches
       BottomMargin - Bottom margin including the gutter, in inches

       HeaderText -   Static text for the page header, this text
                      can be changed dynamically in an event handler

       FooterText -   Static text for the page footer, this text
                      can be changed dynamically in an event handler

       There are two areas on the page. One is within the page margins
       and another is the page including the margin areas. For the lack
       of a better term, these two areas are called Inner and Outer:

         InnerBorderPixels - measured in pixels
                      Thickness of the border inside the margins, in pixels

         OuterBorderPixels - measured in pixels
                      Thickness of the border outside the margins, but still
                      within the non-printable gutter area.

         InnerBorderColor - Color of the border inside the margins
         OuterBorderColor - Color of the border outside the margins
         InnerBackColor - Background color of the page inside the margins
         OuterBackColor - Background color of the margins

  Header, Footer, Band properties:

   First of all you probably realize that there is a property called
   Footer. Then there is a Header. There is also a property called
   "Band." All of these properties are of type TBand. TBand represents
   a paragraph of text with its own set of parameters.

   Header and Footer are probably easy to understand. The Band property
   simply means current paragraph. You can set up the current paragraph
   font, size, etc., and simply call WriteString(text). The text will
   be printed with current settings. Then you change the Band again,
   call WriteString() and the text will be printed with new paragraph
   settings.

   So as you see there are three paragraphs you work with: Header, Footer,
   and the current paragraph exposed through the Band property.

   A paragraph (or band) has the following properties:

         TextAlignment - current text alignment
                      instructs the simple printout component to switch
                      paragraph alignment. This property can be changed
                      in the middle of printing, it will affect subsequent
                      WriteString() calls.
                      This property can be set to: baRight, baCentered,
                      baJustified, and default: baLeft.

         TextFont   - lets you select and change a font for the body of
                      the paragraph.

      Keep in mind that a paragraph usually consists of a box
      (background) and the text (foreground). Box  and text can
      have their own indents, colors, etc:

         BorderPixelSize - paragraph [box] border pixel size
                      By default this is set to 0, so no box is not
                      printed. But the box is still there. It has
                      a white background color. You can get rid of the
                      box by setting Transparent property to TRUE

         Transparent - we just explained this one

         BorderColor - paragraph [box] border color
         ForeColor   - text color
         BackColor   - paragraph [box] color, background color

         IndentLeft  - paragraph indents, in inches
         IndentTop
         IndentRight
         IndentBottom

         TextIndentLeft - text indents within the paragraph
         TextIndentRight
         TextIndentTop
         TextIndentBottom

Lesson 5.
--------
  SimplePrintout also has a couple of Event handlers. Please
  take a look at the DemoProj application to see how they are used.

  PrintPage event is of type UserPrintPageEvent. It is very similar to
  .NET PrintPage event, so that the programmer gets the full control
  before printing each page. Pay attention to the second parameter
  of type UserPrintPageEventArgs. It has these members:

    PageParms: PrintPageEventArgs;
        -- this is the original PrintPageEventArgs, we
           pass it to the user.

    PageNo: Integer;  -- (read only) current page count

    The following five Boolean members are set to FALSE by default.
    However the programmer can set them to TRUE in the event handler
    to indicate specific behaviors:

    PrintoutLastPage: Boolean;
        -- User may set this to TRUE, which means that SimplePrintout
           will print this page and then stop printing.

    BackgroundHandledByUser: Boolean;
        -- If set by user to TRUE it means that SimplePrintout does not
           have to paint the page background, user may have added a
           background picture, for example.

    PageHandledByUser: Boolean;
        -- (set by user) SimplePrintout does not paint the current
           page user handled the page. Note that it still paints the
           header and footer. The next two items let you disable the
           header or the footer, or both.

    HeaderHandledByUser: Boolean; -- indicates that user handled the header
    FooterHandledByUser: Boolean; -- indicates that user handled the header

----------------------------------------------------
Please take a look at the demo project to see the working code. You
may find it easier to cut and paste the code into your project and
build it up from there.

----------------------------------------------------
Enjoy!

Feedback to: [e-mail]
Ref: SimplePrintout for Delphi for .NET (11/19/03)
----------------------------------------------------